Documentation for WBStart V2.0 13-Mar-1996 Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. COPYRIGHT Copyright (C) 1991-96 Stefan Becker No program, document, data file or source code from this software package, neither in whole nor in part, may be included or used in other software packages unless it is authorized by a written permission from the author. NO WARRANTY There is no warranty for this software package. Although the author has tried to prevent errors he can't guarantee that the software package described in this document is 100% reliable. You are therefore using this material at your own risk. The author cannot be made responsible for any damage which is caused by using this software package. DISTRIBUTION This software package is freely distributable. It may be transfered to any media which is used for the distribution of free software like Public Domain disk collections, CDROMs, FTP servers or bulletin board systems. In order to ensure the integrity of this software package distributors should use the original archive file WBStart2_0.lha (file name on Aminet: WBStart.lha). The author cannot be made responsible if this software package has become unusable due to modifications of the archive contents or of the archive file itself. There is no limit on the fee taken by distributors, e.g. for the media costs of floppy disks, streamer tapes or compact discs, or the process of duplicating. Such limits have proven to be harmful to the idea of freely distributable software, e.g. the software package was removed instead of reducing the price of a floppy disk below the limit. Although the author does not impose any limit on these fees he would like to express his personal opinions on this matter: * This software package should be made available to everyone free of charge whenever this is possible. * If you have purchased this software package under normal conditions from a Public Domain dealer on a floppy disk and have paid more than 5DM or US $5 then you have definitely paid too much. Please don't support this improper profit making any longer and switch to a cheaper source as soon as possible. USAGE RESTRICTIONS No program, document, data file or source code from this software package, neither in whole nor in part, may be used on any machine which is used * for the research, development, construction, testing or production of weapons or other military applications. This also includes any machine which is used in the education for any of the above mentioned purposes. * by people who accept, support or use violence against other people, e.g. citizens from foreign countries. I. What is the purpose of this software package? ================================================ WBStart is a package to emulate the Workbenchs' method of starting programs. Emulating this method seems to be easy on the first look, because you only have to load a program, create a process and then send a Workbench startup message to it. But complications arise from this startup message. It contains pointers to memory and directory locks owned by your process and it will not be returned until the newly created Workbench process exits. So your process can't quit until ALL Workbench processes which have been started by your process are finished. If you don't wait the replied messages will go into nowhere land and the man from India will visit you. WBStart solves this problem by using a handler process, which loads the program, creates the process, sends the message and then waits for the reply. You just supply all needed information like program name and arguments in a library call. The handler copies this information so your program can free its resources and exit. II. Installation ================ Just copy the file libs/wbstart.library into your LIBS: directory. The file WBStarter in dev/c/examples is an example program how to use the library. It has the following syntax: WBStarter [ ...] WBStarter tries to start each command as Workbench process without parameters. III. Contents of this software package ====================================== dev/ Autodoc, FD and C header files for wbstart.library. It also contains the source code for the WBStarter example and the DICE link libraries. libs/ wbstart.library. Copy this file to LIBS: src/ Source code for the wbstart.library. It has been written for DICE 3.0 and is included for educational purposes only. Use the command "DMake" to compile it. WBStart.txt This documentation. IV. History =========== 2.0 (13-Mar-1996) - The code has been rewritten from scratch. - The handler has been integrated into a shared library. This means that you don't have to start the handler by hand anymore. It will be started automagically when you try to start a WB program using a library call. This also means an end to all these "I can't start WB programs" error reports resulting from a missing e-Flag on the file L:WBStart-Handler :-) NOTE: The old interface is not supported anymore! You have to rewrite your applications. - Requires OS 3.0 (V39) or better. - Now uses memory pools to reduce memory fragmenting. - Improved WB starter code. It should be almost 100% compatible to the real Workbench now. NOTE: This may result in some incompatibilities to the old WBStart package, so you might have to change some of the input parameters, e.g. in ToolManager Exec objects. - Fixed the problem with variables and aliases. - Fixed the problem with project icons whose default tool had no icon. 1.4 (03-Oct-1993) - If the handler can't duplicate the lock of an argument, it now looks if the argument name ends with a ':'. This type of argument specifies a device and is produced by the Workbench, e.g. if you put an unformatted disk into a drive and use the device icon as argument to the program SYS:System/Format. 1.3 (27-Jun-1993) - The handler now copies the path from the WB process. This solves the problems with programs which use WB2CLI() or similiar functions to get the WB path list, e.g. SYS:System/CLI. My apologies to Michael Sinz, Michael B. Smith and the GRn beta testers. - The handler now scans the path list when it tries to load a program. - The handler now uses NewLoadSeg() instead of LoadSeg(). - Major source cleanup. 1.2 (21-Sep-1992) - Corrected version string. 1.1 (13-Sep-1992) - Fixed weird return bug in WBStart. - Fixed "Insert volume PROGDIR:..." bug. 1.0 (24-Nov-1991) - Initial release V. Contact addresses ==================== Send comments, suggestions or bug reports to: Postal address: Stefan Becker Bonner Ring 68 D-50374 Erftstadt GERMANY EMail: stefanb@yello.ping.de World Wide Web: http://www.ping.de/sites/yello/